ODSettingsExtension

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODSettingsExtension

Superclasses
ODExtension --> ODRefCntObject --> ODObject
Subclasses
none

An object of the ODSettingsExtension class represents a settings modal dialog box--an extension to the Part Info dialog box--that a part editor can create and display.

Description
The Part Info dialog box provides access only to the standard Info properties that all OpenDoc parts have. To allow the user to access properties specific to your parts, you can create a settings extension object to display a settings modal dialog box. If you implement a settings extension object, a button with the title "Settings..." appears in the lower left corner of the Part Info dialog box. When the user clicks this button, your part editor displays a modal dialog box so the user can edit part-specific settings.
The ODSettingsExtension class is an abstract superclass that you can subclass to create a settings extension for a modal dialog box. Once you implement it, OpenDoc accesses your settings extension object by calling your part's AcquireExtension method (page 466), which returns a reference to the extension object. For more information related to extension objects, see the ODExtension class description (page 212).

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODSettingsExtension.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODSettingsExtension, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this settings extension object. The SOM library calls this method when this settings extension object is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this settings extension object's subclass-specific initialization method; see also the InitSettingsExtension method (page 627).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODSettingsExtension, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this settings extension object, including any storage related to additional instance variables initialized in this settings extension object. The SOM library calls this method when this settings extension object is deleted; this method must not fail.

Release
The Release method decrements an object's reference count by 1; it is inherited from the ODRefCntObject class.
void Release ();
If you subclass ODSettingsExtension, you can override this method to release an object and reclaim valuable resources like memory. Your override method must call its inherited method at the beginning of your implementation.
The inherited Release method decrements this settings extension object's reference count by 1. The inherited method may delete this settings extension object from memory (if this object's reference count becomes 0). OpenDoc calls this method when it no longer needs a reference to this settings extension object (for example, after the user has dismissed the Part Info dialog box).

Purge
The Purge method frees memory on request; it is inherited from the ODObject class.
ODSize Purge (in ODSize size);
Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. If you subclass ODSettingsExtension, you must override this method or risk running out of available memory. Your override method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.
Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods
This section presents summary descriptions of the ODSettingsExtension methods, followed by detailed descriptions in alphabetical order.

InitSettingsExtension
Initializes this settings extension object.
ShowSettings
Should display a modal dialog box so the user can edit part-specific settings.

Methods
InitSettingsExtension
ShowSettings